<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Using Localized Data - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level3"><a href="bnara.html">The Example JavaServer Faces Application</a></p>
<p class="toc level3"><a href="bnarb.html">Setting Up a Page</a></p>
<p class="toc level3"><a href="bnarc.html">Using the Core Tags</a></p>
<p class="toc level3"><a href="bnarf.html">Adding UI Components to a Page Using the HTML Component Tags</a></p>
<p class="toc level4"><a href="bnarf.html#bnarg">UI Component Tag Attributes</a></p>
<p class="toc level5"><a href="bnarf.html#bnarh">The <tt>id</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnari">The <tt>immediate</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnarj">The <tt>rendered</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnark">The <tt>style</tt> and <tt>styleClass</tt> Attributes</a></p>
<p class="toc level5"><a href="bnarf.html#bnarl">The <tt>value</tt> and <tt>binding</tt> Attributes</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarm">Adding a Form Component</a></p>
<p class="toc level4"><a href="bnarf.html#bnaro">Using Text Components</a></p>
<p class="toc level5"><a href="bnarf.html#bnarr">Rendering a Text Field with the <tt>inputText</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnars">Rendering a Label with the <tt>outputLabel</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnart">Rendering a Hyperlink with the <tt>outputLink</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnaru">Displaying a Formatted Message with the <tt>outputFormat</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnarv">Rendering a Password Field with the <tt>inputSecret</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarw">Using Command Components for Performing Actions and Navigation</a></p>
<p class="toc level5"><a href="bnarf.html#bnarx">Rendering a Button with the <tt>commandButton</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnary">Rendering a Hyperlink with the <tt>commandLink</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarz">Using Data-Bound Table Components</a></p>
<p class="toc level4"><a href="bnarf.html#bnasb">Adding Graphics and Images with the <tt>graphicImage</tt> Tag</a></p>
<p class="toc level4"><a href="bnarf.html#bnasc">Laying Out Components with the <tt>UIPanel</tt> Component</a></p>
<p class="toc level4"><a href="bnarf.html#bnase">Rendering Components for Selecting One Value</a></p>
<p class="toc level5"><a href="bnarf.html#bnasg">Displaying a Check Box Using the <tt>selectBooleanCheckbox</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnash">Displaying a Menu Using the <tt>selectOneMenu</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnasi">Rendering Components for Selecting Multiple Values</a></p>
<p class="toc level4"><a href="bnarf.html#bnask">The <tt>UISelectItem</tt>, <tt>UISelectItems</tt>, and <tt>UISelectItemGroup</tt> Components</a></p>
<p class="toc level5"><a href="bnarf.html#bnasm">Using the <tt>selectItems</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnasn">Using the <tt>selectItem</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnaso">Displaying Error Messages with the <tt>message</tt> and <tt>messages</tt> Tags</a></p>
<div class="onpage">
<p class="toc level3 tocsp"><a href="">Using Localized Data</a></p>
<p class="toc level4"><a href="#bnasq">Loading a Resource Bundle</a></p>
<p class="toc level4"><a href="#bnasr">Referencing Localized Static Data</a></p>
<p class="toc level4"><a href="#bnass">Referencing Error Messages</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnast.html">Using the Standard Converters</a></p>
<p class="toc level4"><a href="bnast.html#bnasu">Converting a Component's Value</a></p>
<p class="toc level4"><a href="bnast.html#bnasv">Using <tt>DateTimeConverter</tt></a></p>
<p class="toc level4"><a href="bnast.html#bnasx">Using <tt>NumberConverter</tt></a></p>
<p class="toc level3 tocsp"><a href="bnasz.html">Registering Listeners on Components</a></p>
<p class="toc level4"><a href="bnasz.html#bnata">Registering a Value-Change Listener on a Component</a></p>
<p class="toc level4"><a href="bnasz.html#bnatb">Registering an Action Listener on a Component</a></p>
<p class="toc level3 tocsp"><a href="bnatc.html">Using the Standard Validators</a></p>
<p class="toc level4"><a href="bnatc.html#bnate">Validating a Component's Value</a></p>
<p class="toc level4"><a href="bnatc.html#bnatf">Using the <tt>LongRangeValidator</tt></a></p>
<p class="toc level3 tocsp"><a href="bnatg.html">Binding Component Values and Instances to External Data Sources</a></p>
<p class="toc level4"><a href="bnatg.html#bnati">Binding a Component Value to a Property</a></p>
<p class="toc level4"><a href="bnatg.html#bnatj">Binding a Component Value to an Implicit Object</a></p>
<p class="toc level4"><a href="bnatg.html#bnatl">Binding a Component Instance to a Bean Property</a></p>
<p class="toc level3 tocsp"><a href="bnatm.html">Binding Converters, Listeners, and Validators to Backing Bean Properties</a></p>
<p class="toc level3"><a href="bnatn.html">Referencing a Backing Bean Method</a></p>
<p class="toc level4"><a href="bnatn.html#bnatp">Referencing a Method That Performs Navigation</a></p>
<p class="toc level4"><a href="bnatn.html#bnatq">Referencing a Method That Handles an Action Event</a></p>
<p class="toc level4"><a href="bnatn.html#bnatr">Referencing a Method That Performs Validation</a></p>
<p class="toc level4"><a href="bnatn.html#bnats">Referencing a Method That Handles a Value-change Event</a></p>
<p class="toc level3 tocsp"><a href="bnatt.html">Using Custom Objects</a></p>
<p class="toc level4"><a href="bnatt.html#bnatu">Using a Custom Converter</a></p>
<p class="toc level4"><a href="bnatt.html#bnatv">Using a Custom Validator</a></p>
<p class="toc level4"><a href="bnatt.html#bnatw">Using a Custom Component</a></p>
<p class="toc level2 tocsp"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnarf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnast.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnasp"></a><h3>Using Localized Data</h3>
<p><a name="indexterm-1102"></a>JavaServer Faces applications make use of three different kinds of data that can
be localized:</p>
<ul><li><p>Static text, such as labels, alternative text, and tool tips</p></li>
<li><p>Error messages, such as those displayed when validation of user input data fails</p></li>
<li><p>Dynamic data, which is data that must be set dynamically by server-side objects, such as by backing beans</p></li></ul>
<p>This section discusses how to access the first two kinds of data
from the page. <a href="bnaum.html">Performing Localization</a> explains how to produce localized error messages as well as
how to localize dynamic data. If you are not familiar with the basics
of localizing web applications, see <a href="bnaxu.html">Chapter&nbsp;15, Internationalizing and Localizing Web Applications</a>.</p><p>All data in the Duke&rsquo;s Bookstore application have been localized for Spanish, French,
German, and American English. The image map on the first page allows you
to select your preferred locale. See <a href="bnavg.html">Chapter&nbsp;13, Creating Custom UI Components</a> for information on how the
image map custom component was created.</p><p>All the localized data is stored in resource bundles, which are represented as
either <tt>ResourceBundle</tt> classes or text files, usually with the extension <tt>.properties</tt>. For more
information about resource bundles, see <a href="http://java.sun.com/docs/books/tutorial/i18n/index.html">http://java.sun.com/docs/books/tutorial/i18n/index.html</a>.</p><p>After the application developer has produced a resource bundle, the application architect puts
it in the same directory as the application classes. The static text data
for the Duke&rsquo;s Bookstore application is stored in a <tt>ResourceBundle</tt> class called <tt>BookstoreMessages</tt>. The
error messages are stored in another resource bundle called <tt>ApplicationMessages</tt>. After the
resource bundles have been created and before their data can be accessed, they
must be made available to the application, as explained in the following section.</p>

<a name="bnasq"></a><h4>Loading a Resource Bundle</h4>
<p>To reference error messages or static data from the page, you first need
to make available the resource bundle containing the data.</p><p>To make available resource bundles that contain static data, you need to do
one of two things:</p>
<ul><li><p>Register the resource bundle with the application in the configuration file using the <tt>resource-bundle</tt> element, as explained in <a href="bnaxc.html">Registering Custom Localized Static Text</a>.</p></li>
<li><p>Load the resource bundle into the current view using the <tt>loadBundle</tt> tag.</p></li></ul>
<p>Here is an example <tt>loadBundle</tt> tag from <tt>bookstore.jsp</tt>:</p><pre>&lt;f:loadBundle var="bundle"
    basename="messages.BookstoreMessages" /></pre><p><a name="indexterm-1103"></a><a name="indexterm-1104"></a>The <tt>basename</tt> attribute value specifies the fully-qualified class name of the <tt>ResourceBundle</tt> class, which
in this case is located in the <tt>messages</tt> package of the <tt>bookstore</tt> application.</p><p><a name="indexterm-1105"></a>The <tt>var</tt> attribute is an alias to the <tt>ResourceBundle</tt> class. This alias can be
used by other tags in the page in order to access the
localized messages.</p><p>In the case of resource bundles that contain error messages, you need to
register the resource bundle with the application in the configuration file using the
<tt>message-bundle</tt> element, as explained in <a href="bnaxb.html">Registering Custom Error Messages</a>. One exception is if you are referencing
the error messages from the input component attributes described in <a href="#bnass">Referencing Error Messages</a>. In that case,
you load the resource bundles containing these messages in the same way you
load resource bundles containing static text.</p>

<a name="bnasr"></a><h4>Referencing Localized Static Data</h4>
<p>To reference static localized data from a resource bundle, you use a value
expression from an attribute of the component tag that will display the localized
data. You can reference the message from any component tag attribute that is
enabled to accept value expressions.</p><p><a name="indexterm-1106"></a><a name="indexterm-1107"></a>The value expression has the notation <tt>var.message</tt>, in which <tt>var</tt> matches the <tt>var</tt>
attribute of the <tt>loadBundle</tt> tag or the <tt>var</tt> element in the configuration file, and
<tt>message</tt> matches the key of the message contained in the resource bundle, referred
to by the <tt>var</tt> attribute. Here is an example from <tt>bookstore.jsp</tt>:</p><pre>&lt;h:outputText value="#{bundle.Talk}"/></pre><p>Notice that <tt>bundle</tt> matches the <tt>var</tt> attribute from the <tt>loadBundle</tt> tag and that
<tt>Talk</tt> matches the key in the <tt>ResourceBundle</tt>.</p><p>Another example is the <tt>graphicImage</tt> tag from <tt>chooselocale.jsp</tt>:</p><pre>&lt;h:graphicImage id="mapImage" url="/template/world.jpg"
     alt="#{bundle.ChooseLocale}"
    usemap="#worldMap" /></pre><p>The <tt>alt</tt> attribute is enabled to accept value expressions. In this case, the
<tt>alt</tt> attribute refers to localized text that will be included in the alternative
text of the image rendered by this tag.</p><p>See <a href="bnavu.html">Creating Custom Component Classes</a> and <a href="bnavu.html#bnavy">Enabling Component Properties to Accept Expressions</a> for information on how to enable value binding on
your custom component&rsquo;s attributes.</p>

<a name="bnass"></a><h4>Referencing Error Messages</h4>
<p>A JavaServer Faces page uses the <tt>message</tt> or <tt>messages</tt> tags to access
error messages, as explained in <a href="bnarf.html#bnaso">Displaying Error Messages with the <tt>message</tt> and <tt>messages</tt> Tags</a>.</p><p>The error messages that these tags access include:</p>
<ul><li><p>The standard error messages that accompany the standard converters and validators that ship with the API. See section 2.5.4 of the JavaServer Faces specification, version 1.2, for a complete list of standard error messages.</p></li>
<li><p>Custom error messages contained in resource bundles registered with the application by the application architect using the <tt>message-bundle</tt> element in the configuration file.</p></li>
<li><p>Custom error messages hard coded in custom converter and validator classes.</p></li></ul>
<p>When a converter or validator is registered on an input component, the appropriate
error message is automatically queued on the component.</p><p>A page author can override the error messages queued on a component by
using the following attributes of the component&rsquo;s tag:</p>
<ul><li><p><tt>converterMessage</tt>: References the error message to display when the data on the enclosing component can not be converted by the converter registered on this component.</p></li>
<li><p><tt>requiredMessage</tt>: References the error message to display when no value has been entered into the enclosing component.</p></li>
<li><p><tt>validatorMessage</tt>: References the error message to display when the data on the enclosing component cannot be validated by the validator registered on this component.</p></li></ul>
<p>All three attributes are enabled to take literal values and value expressions. If
an attribute uses a value expression, this expression references the error message in
a resource bundle. This resource bundle must be made available to the application
in one of the following ways:</p>
<ul><li><p>By the page author using the <tt>loadBundle</tt> tag</p></li>
<li><p>By the application architect using the <tt>resource-bundle</tt> element in the configuration file</p></li></ul>
<p>Conversely, the <tt>message-bundle</tt> element must be used to make available to the application
those resource bundles containing custom error messages that are queued on the component
as a result of a custom converter or validator being registered on the
component.</p><p>The <tt>bookcashier.jsp</tt> page includes an example of the <tt>requiredMessage</tt> attribute using a value
expression to reference an error message:</p><pre>&lt;h:inputText id="ccno" size="19"
    required="true"
    requiredMessage="#{customMessages.ReqMessage}" >
    ...
&lt;/h:inputText>
&lt;h:message styleClass="error-message"  for="ccno"/></pre><p>The value expression that <tt>requiredMessage</tt> is using in this example references the error
message with the <tt>ReqMessage</tt> key in the resource bundle, <tt>customMessages</tt>.</p><p>This message replaces the corresponding message queued on the component and will display
wherever the <tt>message</tt> or <tt>messages</tt> tag is placed on the page.</p><p>See <a href="bnaxb.html">Registering Custom Error Messages</a> and <a href="bnaxc.html">Registering Custom Localized Static Text</a> for information on how to use the <tt>message-bundle</tt> and
<tt>resource-bundle</tt> element to register resource bundles that contain error messages.</p>
         </div>
         <div class="navigation">
             <a href="bnarf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnast.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

